home *** CD-ROM | disk | FTP | other *** search
/ Aminet 2 / Aminet AMIGA CDROM (1994)(Walnut Creek)[Feb 1994][W.O. 44790-1].iso / Aminet / dev / c / RConfig.lha / RConfig_v1.1 / docs / alloca.doc next >
Encoding:
Text File  |  1992-09-13  |  4.7 KB  |  133 lines
  1. TYPE
  2.     alloca(R) - Memory Allocation
  3.  
  4. NAME
  5.     alloca - allocate a block of auto-freeing system memory
  6.  
  7. SYNOPSIS
  8.     #include <alloca.h>
  9.     void *alloca(long *var, size_t _size);      /* __SAFE_ALLOCA */
  10.  
  11.     #include <alloca.h>
  12.     void *alloca(size_t _size);                 /* __RISKY_ALLOCA */
  13.  
  14. DESCRIPTION
  15.     alloca() is an Amiga (machine dependent) implementation of the Unix
  16.     alloca() function, allocating space from the system heap (placing only
  17.     control information on the run-time stack) which will be automatically
  18.     reclaimed upon the procedure's exit.
  19.  
  20. NOTES
  21.     alloca() only maintains an explicit list of alloca() allocated blocks
  22.     if setjmp(),longjmp() are used.  Otherwise, an implicit linked list
  23.     of stack frames using an actual procedure stack is used.
  24.  
  25.     alloca() "detours" the calling procedure's exit to a clean-up
  26.     function.  There are two ways of performing the detour--one
  27.     risky and one safe.  It's up to you to weigh the advantages/
  28.     disadvantages, and decide which to use.  Those "features" common
  29.     to both implementations are marked "(common)".  Please refer to
  30.     the source for additional information.
  31.  
  32.  
  33.     The RISKY Version
  34.     ~~~~~~~~~~~~~~~~~
  35.         Advantage(s)
  36.         ~~~~~~~~~~~~
  37.         o   Syntax (call style) follows Unix convention, and simplifies
  38.             porting Unix programs which depend on this function.
  39.         o   Automatically reclaim temporary storage upon a procedure's
  40.             exit. (common)
  41.         o   Net effect is no stack usage. (common)
  42.         o   Compatible with RConfig's setjmp()/longjmp(). (common)
  43.  
  44.  
  45.         Disadvantage(s)
  46.         ~~~~~~~~~~~~~~~
  47.         o   Always assumes that a5 points to the top of the current stack
  48.             frame.  If a5 gets munged (or is invalid), the results are
  49.             unpredictable.
  50.         o   If a5 points to a higher stack frame, instead of the current
  51.             one, automaticatic reclamation of alloca()-memory is delayed,
  52.             until control returns to the higher procedure, and it exits.
  53.  
  54.  
  55.         Technical Notes
  56.         ~~~~~~~~~~~~~~~
  57.         As stated previously, there are certain conditions required for
  58.         alloca.a68 to work (or work efficiently).
  59.  
  60.         o   register a5 should be valid and point to the top of a stack
  61.             frame when alloca() is called
  62.         o   it is desirable to have link..unlk pairs generated even
  63.             when there are no local variables (disable -sn optimization)
  64.  
  65.  
  66.     The SAFE Version
  67.     ~~~~~~~~~~~~~~~~
  68.         Advantage(s)
  69.         ~~~~~~~~~~~~
  70.         o   No dependency on register a5, so you can compile with -sn
  71.             optimization.
  72.         o   Automatically reclaim temporary storage upon a procedure's exit.
  73.             (common)
  74.         o   Net effect is no stack usage. (common)
  75.         o   Compatible with RConfig's setjmp()/longjmp(). (common)
  76.  
  77.  
  78.         Disadvantage(s)
  79.         ~~~~~~~~~~~~~~~
  80.         o   Syntax (call style) does not follow convention (ie non-portable).
  81.  
  82.  
  83.         Technical Notes
  84.         ~~~~~~~~~~~~~~~
  85.         The macro (in alloca.h) passes the function's return address to
  86.         alloca()...hence, the need for a dummy parameter (if one doesn't
  87.         exist) in order to reference this item on the stack.
  88.  
  89.  
  90.         Usage
  91.         ~~~~~
  92.         Due to the difference in call style, this version requires some
  93.         code changes.  First, you must define SAFE_ALLOCA before including
  94.         "alloca.h".
  95.  
  96.             #define __SAFE_ALLOCA
  97.             #include "alloca.h"
  98.  
  99.         Second, alloca() is now passed the name of the calling function's
  100.         first parameter, and if the function has none, a dummy parameter must
  101.         be added.  An example:
  102.  
  103.             /*
  104.              *  Using this "old" style declaration, Aztec cc won't
  105.              *  complain, unless (of course) you've prototyped it otherwise.
  106.              */
  107.             ReturnType ProcedureName( VariableOrDummyParameter )
  108.                 int VariableOrDummyParameter;
  109.               {
  110.                 YourPointerType p;
  111.  
  112.                 p = (YourPointerType) alloca( VariableOrDummyParameter, size );
  113.               }
  114.  
  115.         Lastly, don't forget to link with the correct version of the object
  116.         code.
  117.  
  118.  
  119. SEE ALSO
  120.     setjmp(), longjmp(), stkchk()
  121.  
  122. DIAGNOSTICS
  123.     If alloca() cannot allocate the requested size block, it returns a null
  124.     pointer.  Otherwise, a pointer to the request size block is returned.
  125.  
  126. REFERENCES
  127.     DYNASTACK91  -  Improved stack checking code, with dynamic stack resizing.
  128.                     Copyright 1991 by Anthon Pang; Copyright 1986,1987 by
  129.                     Manx Software Systems, Inc.  December 1991.
  130.  
  131.     GNUALLOC86   -  A (mostly) portable public-domain implementation of
  132.                     'alloca.c' included in the GNU distribution, circa 1986.
  133.